home *** CD-ROM | disk | FTP | other *** search
/ Video Toaster 4.2 / Video Toaster v4.2.iso / programs / documentation / arexx / editorarexx.doc < prev    next >
Text File  |  1996-01-03  |  21KB  |  558 lines
  1. Editor ARexx Documentation              Nov 21 1995       Editor version 4.1
  2.  
  3. The Video Toaster's Editor interface is controlled through an entirely
  4. separate program, Edit.  It has its own ARexx port, which is configured as
  5. a function host.  The port name is PROJECT_REXX_PORT, and the functions
  6. it responds to are documented below.  Although arexx programs can be
  7. executed (asynchronously) from within a sequence, the editor itself is
  8. preoccupied with its sequencing duties, and will not respond to any rexx
  9. messages sent to it until after the sequence is done playing.  The upshot
  10. of this is that you must put your rexx croutons at the end of a sequence if
  11. you want them to talk to the editor. Have fun.
  12.  
  13.  
  14. "CROUTONNAME"   returns crouton name
  15.                 ARGS:   [Row,Column]
  16.  
  17.  
  18. "CROUTONSPOT"   return position in grid for current crouton
  19.                 ARGS: NONE
  20.  
  21.  
  22. "CROUTONTYPE"   Return Crouton Type
  23.                 ARGS:   [Row,Column]
  24.  
  25. "CROUTONSINPROJECT" Return total number of croutons in the current project.
  26.  
  27. "CROUTONPICK"   Pick Crouton -- Selects Crouton
  28.                 ARGS:   0 args ==> deselect all
  29.                 ARGS:   1 args ==> Number OR "FIRST" or "LAST"
  30.                 ARGS:   2 args ==> Row,Column
  31.  
  32.  
  33. "CROUTONLOAD"   Load Crouton -- Load crouton into project and place at the end.  If
  34.                 INSERT keyword is included, will instead insert after the currently
  35.                 selected crouton (if none is selected, will be placed at the
  36.                 beginning).
  37.                 ARGS:   crouton name (full path) [INSERT]
  38.  
  39. "CROUTONDELETE"        Deletes currently selected crouton
  40.                 ARGS: NONE
  41.  
  42. "CROUTONTIME"        Returns the start time for the selected crouton, measured from the
  43.                 start of the project.  Value is in fields.  This value is useful
  44.                 for locking a crouton (using the DELAY tag).
  45.                 ARGS: NONE
  46.  
  47. "CROUTONRUN"    Run Crouton without adding to project
  48.                 ARGS:   CroutonName
  49.  
  50. "CROUTONSELECTED" Return 1 if crouton is selected.
  51.                 ARGS:  [Row,Column]
  52.  
  53. "CROUTONSTOP"   Aborts currently playing crouton (clip)
  54.                 ARGS:  none
  55.  
  56.  
  57. "CROUTONGETTAG" Return Tag value, may be 0 if tag doesn't exist OR tag has value of 0
  58.                 ARGS:   Tag name
  59.  
  60.  
  61. "CROUTONSETTAG" Set crouton tag value
  62.                 ARGS: Tag name, Value
  63.  
  64. "CROUTONSAVETAG"        Mark the named tag for the currently selected crouton as
  65.                         needing to be saved with the project the next time it's
  66.                         saved.  This marking is not permanent -- if the project
  67.                         is reloaded, the normal strategy is once again applied to
  68.                         determine which tags get saved.
  69.                 ARGS: Tag name
  70.  
  71. "CROUTONCHECKTAG"       Check existance of tag in crouton, return size
  72.                 ARGS:   Tag name
  73.  
  74. NOTE:  It appears that this function, now debugged, always succeeds - so
  75. please check tag validity with CROUTONTYPE, etc. before applying some
  76. irrelevant or illegal tag.  For example, use CROUTONTYPE to identify
  77. that a crouton is a Framestore so you don't foolishly apply a AUDIOVOLUME1
  78. to it!
  79.  
  80.  
  81. ========= CRNUMxxxx functions =========
  82.  
  83. These work very similar to their CROUTONxxxx counterparts, but do not operate on the
  84. currently selected crouton.  Instead, they take an additional argument which specifies
  85. the crouton (by number).  The croutons in the project are numbered starting at 0.
  86. These functions also leave unchanged any crouton(s) which may have been previously
  87. selected/highlighted.
  88.  
  89. These have been provided to prevent the unpredictable results which can occur when
  90. someone uses the Editor to highlight/unhighlight croutons while an ARexx script is
  91. executing.  These functions remove this possibility by using a specification
  92. mechanism that the user cannot tamper with.
  93.  
  94. "CRNUMTYPE"     Return type of the specified crouton in project (not currently selected one).
  95.                 ARGS: Crouton number
  96.  
  97. "CRNUMGETTAG"   Return Tag value for specified crouton in project (not currently selected one).
  98.                 May be 0 if tag doesn't exist OR tag has value of 0
  99.                 ARGS: Crouton number, Tag name
  100.  
  101. "CRNUMSETTAG"   Set tag value for specified crouton in project (not currently selected one).
  102.                 ARGS: Crouton number, Tag name, Value
  103.  
  104. "CRNUMSAVETAG"  Mark the named tag for the specified crouton as
  105.                 needing to be saved with the project the next time it's
  106.                 saved.  This marking is not permanent -- if the project
  107.                 is reloaded, the normal strategy is once again applied to
  108.                 determine which tags get saved.
  109.                 ARGS: Crouton number, Tag name
  110.  
  111. "CRNUMCHECKTAG" Check existance of tag in specified crouton, return size
  112.                 ARGS: Crouton number, Tag name
  113.  
  114. "PROJECTLOAD"   Load Project
  115.                 ARGS:   Project name (full path)
  116.  
  117.  
  118. "PROJECTSAVE"   Save Project
  119.                 ARGS:   Project name (full path)
  120.  
  121.  
  122. "PROJECTPLAY"   Play Project
  123.                 ARGS:   none
  124.  
  125.  
  126. "PROJECTUPDATE" Update Project after modifying croutons or tags (updates total
  127.                 running time display)
  128.                 ARGS:   none
  129.  
  130.  
  131. "FLYERDRIVE"    Return flyer drive name based on index in internal list, or ""
  132.                 ARGS: Drive number, starting at 0
  133.  
  134.  
  135. "FLYERSTATUS"   Return flyer recording status/error code, useful to determine if
  136.                 Flyer has failed/stopped recording, and if so why.
  137.                 The codes are listed below (FERR_xxx).
  138.                 ARGS: NONE
  139.  
  140. "FLYEROUT"      Adjust Toaster settings for inputs 3 and 4
  141.                 ARGS:[value] (if value is omitted, current setting is returned)
  142.                         Setting is bit mask for inputs 3(bit 0) and 4(bit 1). Bit set means
  143.                         Flyer has that input, 0 means it is live toaster input.
  144.  
  145. "RECORDADD"     Record fields into a flyer clip, will append fields into an
  146.                 existing clip, or create a new one.  The clip is always closed and usable
  147.                 after this command.  Although the flyer can only record clips in whole
  148.                 (4-field) NTSC color-frames, this command will copy the correct fields
  149.                 into the clip, temporarily padding the clip on the end to make a complete
  150.                 color-frame if necessary.
  151.                 ARGS: ClipName, # of Fields [, Source, Compression Mode]
  152.                         omitting source or mode will use last selected mode, note that all
  153.                         clips must have full flyer VOLUME name included.
  154.  
  155.  
  156. "RECORDCLIP"    Record a named flyer clip, won't overwrite existing clip w/ same name
  157.                 This places Flyer into record mode.  When finished recording, you MUST
  158.                 place it back into play mode.  To do this, use RECORDSTOP (even if you
  159.                 detect with FLYERSTATUS that recording has stopped on its own).
  160.                 ARGS: ClipName [Name, # of Fields, Source, Compression Mode]
  161.                         if fields=0, recording continues 'til drive is full omitting source
  162.                         or mode will use last selected mode, note that all clips must have
  163.                         full flyer VOLUME name included. This command will probably not be able
  164.                         to record clips with an uneven number of color-frames.
  165.  
  166.  
  167. "RECORDPAUSE"   Pause Recording
  168.                 ARGS: Pause=1 for Pause, 0 for resume
  169.  
  170.  
  171. "RECORDSTOP"    Stop Recording and put Flyer back into play mode.  You MUST do this even
  172.                 if the Flyer stops recording on its own, or the Editor will NOT be able
  173.                 to play clips or do sequencing!
  174.                 ARGS: none
  175.  
  176.  
  177. "MAKEICON"      Create an icon for a flyer clip, optionally make 'Flyer Still'
  178.                 icon for 4=field clips by adding 'STILL' keyword.
  179.                 ARGS: ClipName [, Field, ['STILL'] ]
  180.  
  181.  
  182. "REQ_BUTTONS"   Put up requester with title and up to 4 labelled buttons.
  183.                 "Defaults" is a string of 0/1's specifying initial button
  184.                 states.  Returns string of 0/1's for each final button state
  185.                 or "CANCEL" if user cancels requester.  Strings are only as
  186.                 long as the number of buttons being used; first digit is
  187.                 for the first button.
  188.                 ARGS: Title, Defaults, label1,[label2,[label3,[label4]]]
  189.  
  190.  
  191. "REQ_ERROR"     Display error message at top of screen
  192.                 ARGS: String
  193.  
  194.  
  195. "REQ_FLYERJOG"  Put up a Flyer clip jog/shuttle requester
  196.                 ARGS: Title, Pathname, [points]
  197.  
  198.                 Put up requester with a slider to allow user to jog/shuttle
  199.                 thru a Flyer clip to pick a specific time.  This works by
  200.                 just specifying a pathname (volume:name) for the clip.  It
  201.                 does not need to be in the current sequence.  You MUST include
  202.                 the volume name, and it must NOT be the device name.  In other
  203.                 words "FlyerA0:abc" is proper, but "FA0:abc" is not.
  204.  
  205.                 "Points" can be 1 or 2.  Default if omitted is 1.  This selects
  206.                 whether a 1-knob or 2-knob slider will be presented.  This
  207.                 function returns "CANCEL" if user presses Cancel button, otherwise
  208.                 it returns the time value as a string.  For 2-knob version, it
  209.                 returns the two time strings separated by a space.
  210.  
  211.                 This function will not affect the tags of any croutons in the
  212.                 project, so if the intent is to do this, you must use the output
  213.                 of this function and CROUTONSETTAG to actually change a
  214.                 crouton's tags.
  215.  
  216.                 Note that the time values used in the editor are usually displayed
  217.                 in drop-frame format.  The time values returned by this function
  218.                 are non-drop format -- this means the values returned are actual
  219.                 numbers of frames.  The 2nd point, however, is EXCLUSIVE.  This
  220.                 means that the 2nd time returned is not exactly the time shown in
  221.                 the 2nd time box, but is adjusted so it includes the user's desired
  222.                 last frame.  This also makes the TAG_DURATION easy to compute:
  223.                 2nd time - 1st time.
  224.  
  225. "REQ_NUMBER"    Put up number requester with optional min,max limits
  226.                 Returns "CANCEL" if user presses Cancel button.
  227.                 ARGS: Title, [num,[min,[max]]]
  228.  
  229.  
  230. "REQ_STRING"    String requester
  231.                 Returns "CANCEL" if user presses Cancel button.
  232.                 ARGS: Title, [String]
  233.  
  234.  
  235. "REQ_TELL"      Put up requester with title and up to 3 lines, return 1 or 0
  236.                 ARGS: Title, [line1,[line2,[line3]]]
  237.  
  238.  
  239. "REQ_TIME"      Time code string requester -- alters/returns time string like 'HH:MM:SS:FF'
  240.                 Returns "CANCEL" if user presses Cancel button.
  241.                 ARGS: Title, [time]
  242.  
  243.  
  244. "REQ_OPEN"      Open an asynchronous requester with title and up to 3 lines, return nothing
  245.                 ARGS: Title, [line1,[line2,[line3]]]
  246.  
  247.  
  248. "REQ_CLOSE"     Close asynchronous opened with REQ_OPEN
  249.                 ARGS: NONE
  250.  
  251.  
  252. "STARTFILEREQ"  Open Grazer as file requester, use QUERYFILEREQ to query result
  253.                 ARGS: Title, Initial path, Initial file
  254.  
  255.  
  256. "QUERYFILEREQ"  Return result of Grazer as file requester:
  257.                                 "" if requester is up, 0 if canceled, or name
  258.                 ARGS: NONE
  259.  
  260.  
  261. "CURRENTPATH"   Return current path in bottom grazer window, if any
  262.                 ARGS: NONE
  263.  
  264.  
  265. "GETSCREEN"     Return editor/switcher screen address
  266.                 ARGS: NONE
  267.  
  268.  
  269. "SET_VIEW"      Change views between project/files, project/Switcher, etc.
  270.                 Returns the code for the previous mode
  271.                 ARGS: View# 0-5 though 3 is not supported, 5 is no top window, ARexx-only mode
  272.  
  273.                 View                        Code
  274.                 ----------------            ----
  275.                 Files/Files                  0
  276.                 Project                      1
  277.                 Project/Files                2
  278.                 Project/Project              3
  279.                 Project/Switcher             4
  280.  
  281.  
  282. "ADDPROGRAM"    Add a Name and command to 'Programs' popup
  283.         ARGS:   Program Name(28 chars max), command string(127 chars max), flags
  284.                 where:
  285.                         Name appears in popup, runs command as either rexx or dos script
  286.                         depending on flags bit 0 (i.e.  1 for ARexx, 0 for dos).  Returns
  287.                         number in popup sequence.       N.B. The editor waits for Dos commands
  288.                         to return, thus an app. that will not finish immediately should
  289.                         be preceeded by the 'run' command.
  290.  
  291.                 Note: DOS execution may be broken???
  292.  
  293.  
  294. "REMPROGRAM"    Remove user-program from 'Programs' popup
  295.                 ARGS: program index (position in popup) as returned by Addprogram
  296.  
  297.  
  298. "PROGRAMCMD"    return user-program command string
  299.                 ARGS: program index (position in popup) as returned by Addprogram
  300.  
  301.  
  302. "PROGRAMNAME"   return user-program name as it appears in Programs popup
  303.                 ARGS: program index (position in popup) as returned by Addprogram
  304.  
  305. "PROGRAMNUM"    return program index (position in popup)
  306.                 ARGS: User-program command string
  307.  
  308.  
  309. "ADDTOOL"       Add a Name and command to 'Tools' popup
  310.         ARGS:   Program Name(28 chars max), command string(127 chars max), flags
  311.                 where:
  312.                         Name appears in popup, runs command as either rexx or dos script
  313.                         depending on flags bit 0 (i.e.  1 for ARexx, 0 for dos).  Returns
  314.                         number in popup sequence.       N.B. The editor waits for Dos commands
  315.                         to return, thus an app. that will not finish immediately should
  316.                         be preceeded by the 'run' command.
  317.  
  318.                 Note: DOS execution may be broken???
  319.  
  320.  
  321. "REMTOOL"       Remove user-program from 'Tools' popup
  322.                 ARGS: program index (position in popup) as returned by Addtool
  323.  
  324.  
  325. "TOOLCMD"       return user-program command string
  326.                 ARGS: program index (position in popup) as returned by Addtool
  327.  
  328. "TOOLNAME"      return user-program name as it appears in Tool popup
  329.                 ARGS: program index (position in popup) as returned by Addprogram
  330.  
  331. "TOOLNUM"       return Tool index (position in popup)
  332.                 ARGS: User-program command string
  333.  
  334. "TBC"           Adjust Flyer TBC settings
  335.                 ARGS: Setting,[value] (if value is omitted, current setting is returned
  336.                         Setting May be 1 of: (cap.s are min. abbrev.)
  337.                                 Bright(-64 - 63), Contrast(0-127), Saturation(0-127),
  338.                                 HUe(-64-63), Fader(0-255), Phase(0-2047),
  339.                                 HorizAdj(0-909), Key(0-3), Mode(0-2)(for keyer),
  340.                                 Encoder(0-15), Decoder(0-8),
  341.                                 Termination(0-31), Input(0-3), Out(0,1)
  342.  
  343. Here are the tag names you can use with the crouton tag commands.
  344. Internally, they correspond to ordered numbers which may have the first bit
  345. set to indicate whether the values are LONGs or variable length tables.
  346. The meaning of the tags should be evident from their names, and if they're
  347. not, that is a good indication that you shouldn't mess with them, and they
  348. probably won't do anything if you do.
  349.  
  350. Version
  351. Revision
  352. AAeffect
  353. NonAAeffect
  354. KillInterfaceNonAA
  355. KillInterfaceAA
  356. ButtonELHlogic
  357. CustomButtonELHlogic
  358. NumberOfAnims
  359. RequestFileName
  360. AnimFiles
  361. Frames
  362. FieldSync
  363. VariableSpeeds
  364. ForcePlayForward
  365. ForcePlayReverse
  366. LoopAnims
  367. AnimControl
  368. AudioFastSamples
  369. AudioMediumSamples
  370. AudioSlowSamples
  371. AudioFiles
  372. AudioControl
  373. PauseTimes
  374. LatchColors
  375. TransparentColors
  376. PaletteColors
  377. Equations
  378. Encoder
  379. VerticalScroll
  380. ReverseTime
  381. ReverseButtLog
  382. ReverseCustomButtLog
  383. KeyMode
  384. MatteColor
  385. CustomMatteColor
  386. BorderColor
  387. CustomBorderColor
  388. LineNumbers
  389. LineNumberPlane
  390. ForceFreeze4
  391. ForceFreeze8
  392. ForceLive
  393. ForceLumKeyOn
  394. ForceLumKeyOff
  395. ForceLumKeyOnBlack
  396. ForceLumKeyOnWhite
  397. BadDefaultFX
  398. LoadPictures
  399. FadeInDuration
  400. FadeOutDuration
  401. DigitalFX
  402. TimeMode
  403. LUT
  404. DigitalPairs
  405. LatchAM
  406. LatchBM
  407. LatchIS
  408. HonorPreviewOverLay
  409. ForceDefaultMatte
  410. TurnAudioFilterOff
  411. AudioStartField
  412. NumAudioFields
  413. ISandClipPause
  414. Interlaced
  415. FirstFieldNTSCII
  416. BounceILBM
  417. LatchRanges
  418. LatchList
  419. TransparentRanges
  420. TransparentList
  421. Color0Transparent
  422. AbortIfSlow
  423. NumSkipFieldsAtEnd
  424. TBarDoesAuto
  425. DoNotStompSprite
  426. AbortLoopAtEnd
  427. NonAAremap
  428. 100PercentWhiteMatte
  429. UseEffectColor
  430. LoopCount
  431. CroutonType
  432. TimeLine
  433. IndexID
  434. FCountMode
  435. VariableFCount
  436. SlowFCount
  437. MedFCount
  438. FastFCount
  439. VariableFCount68000
  440. SlowFCount68000
  441. MedFCount68000
  442. FastFCount68000
  443. NumFields
  444. StartTime
  445. DescriptorList
  446. AboutList
  447. CommentList
  448. AlgoFXtype
  449. AlgoFXborder
  450. NumFramesSlow
  451. NumFramesMedium
  452. NumFramesFast
  453. NumFramesVariable
  454. Page
  455. Speed
  456. Delay
  457. Duration
  458. AudioAttack
  459. AudioDecay
  460. RecFields
  461. AudioOn
  462. AudioStart
  463. AudioDuration
  464. ClipStartField
  465. FadeInVideo
  466. MaxDuration
  467. VideoSource
  468. LoadedSlices
  469. OriginalLocation
  470. AudioVolume1
  471. AudioVolume2
  472. AudioPan1
  473. AudioPan2
  474. PanelMode
  475. ColorMode
  476. CycleMode
  477. DataMode
  478. AdjustedVideoStart
  479. AdjustedVideoDuration
  480. Asynchronous
  481. CommandLine
  482. SMPTEtime
  483. TBarPosition
  484. HoldFields
  485. TakeOffset
  486. ASourceLen
  487. BSourceLen
  488. AudioFadeFlags
  489.  
  490.  
  491. Here are the Error codes returned by the FLYERSTATUS command.
  492.  
  493. /*** General Flyer Errors ***/
  494. #define FERR_OKAY               0x00    /* All went well */
  495. #define FERR_CMDFAILED          0x01    /* Command failed for some reason */
  496. #define FERR_BUSY               0x02    /* Still in progress */
  497. #define FERR_ABORTED            0x03    /* User abort */
  498. #define FERR_BADPARAM           0x04    /* Bad command parameter */
  499. #define FERR_BADCOMMAND         0x05    /* Command not defined/supported */
  500. #define FERR_BADVIDHDR          0x06    /* Ran out of video - no header detected */
  501. #define FERR_WRONGMODE          0x07    /* Wrong play/rec mode for action */
  502. #define FERR_OLDDATA            0x08    /* Incompatible data */
  503. #define FERR_NOAUDIOCHAN        0x09    /* No free audio channel(s) */
  504. #define FERR_CHANINUSE          0x0A    /* Video/SCSI channel not available */
  505. #define FERR_BADFLDHAND         0x0B    /* Bad field handle */
  506. #define FERR_CLIPLATE           0x0C    /* A/V clip started late */
  507.  
  508. /*** Flyer Internal Errors ***/
  509. #define FERR_NOTASKS            0x10    /* No SCSI tasks available for use */
  510. #define FERR_LISTCORRUPT        0x11    /* Internal list corrupt */
  511. #define FERR_NOTINRANGE         0x12    /* Internal list error */
  512. #define FERR_EEFAILURE          0x13    /* EEPROM failure */
  513. #define FERR_NOFINDERS          0x14    /* No FrameFinders available for use */
  514. #define FERR_BADMODULE          0x1F    /* Incompatible module provided */
  515.  
  516. /*** FileSystem Errors ***/
  517. #define         FIRSTFSERR      0x20
  518. #define FERR_OBJNOTFOUND        0x20    /* Could not find file/dir */
  519. #define FERR_FULL               0x21    /* Drive full */
  520. #define FERR_DIRFULL            0x22    /* Directory full */
  521. #define FERR_EXHAUSTED          0x23    /* Directory list exhausted */
  522. #define FERR_FSFAIL             0x24    /* FileSystem failure */
  523. #define FERR_WRONGTYPE          0x25    /* Wrong type of object */
  524. #define FERR_UNFORMATTED        0x26    /* Drive not high-level formatted */
  525. #define FERR_EXCLUDED           0x27    /* Exclusive lock prevented action */
  526. #define FERR_OUTOFRANGE         0x28    /* Seek beyond bounds */
  527. #define FERR_CANTEXTEND         0x29    /* End of file, and cannot extend file */
  528. #define FERR_PROTECTED          0x2A    /* Drive write-protected */
  529. #define FERR_DIFFERENT          0x2B    /* Grips are different objects */
  530. #define FERR_EXISTS             0x2C    /* File already exists */
  531. #define FERR_NOMEM              0x2D    /* Out of storage */
  532. #define FERR_DELPROT            0x2E    /* Delete-protected file */
  533. #define FERR_READPROT           0x2F    /* Read-protected file */
  534. #define FERR_WRITEPROT          0x30    /* Write-protected file */
  535. #define FERR_INUSE              0x31    /* Disk/object in use */
  536. #define FERR_DIRNOTEMPTY        0x32    /* Directory was not empty */
  537. #define         LASTFSERR       0x32
  538.  
  539. /*** SCSI Errors ***/
  540. #define FERR_SELTIMEOUT         0x40    /* SCSI Time-out -- no drive */
  541. #define FERR_BADSTATUS          0x41    /* Bad status after executing command */
  542.  
  543. /*** Sequencing Errors ***/
  544. #define FERR_WRONGDATATYPE      0x60    /* Asked for improper type of data from clip */
  545. #define FERR_DRIVEINCAPABLE     0x61    /* Using video clip from a non-video drive */
  546. #define FERR_NO_BROLLDRIVE      0x62    /* No video B-roll drive found */
  547. #define FERR_HEADFAILED         0x63    /* A/B head missing/problem */
  548.  
  549. /*** Amiga Library Errors ***/
  550. #define FERR_NOCARD             0x70    /* Flyer card specified does not exist */
  551. #define FERR_LIBFAIL            0x71    /* Library failed to pass command to Flyer */
  552. #define FERR_ASYNCFAIL          0x72    /* An asynchronous command failed */
  553. #define FERR_VOLNOTFOUND        0x73    /* Volume name not found */
  554. #define FERR_NOFREECMD          0x74    /* Library<->Flyer RAM clogged */
  555. #define FERR_BADID              0x75    /* Illegal async ID */
  556.  
  557. #define FERR_LIMIT              0x7F
  558.